docs(jpa-patterns): recommend UUIDv7 for entity primary keys - #3

Thanks, this is a good addition and the section is worth having.

Two things to fix before I can merge.

The first is the version claim. UuidGenerator.Style only got VERSION_6 and VERSION_7 in Hibernate 7.0. I unpacked 6.5.2, 6.6.5 and 7.0.0 to be sure: 6.5 has neither VERSION_7 nor the algorithm() member, and 6.6 added algorithm() but ships no v7 strategy class, so there you would have to write your own UuidValueGenerator. The sample as written needs Hibernate 7.0+.

That matters more than a number in the comment, because of what the Boot BOM pulls in. Boot 3.3 gets Hibernate 6.5, 3.4 and 3.5 get 6.6, and 7.x only arrives with Boot 4.0. So for anyone on Boot 3.x, which is most people reading this today, the @PrePersist variant is the path they will actually take. I would put it first and label the annotation version as Hibernate 7 / Boot 4.

The second is the framing. "Recommended for most new entities" claims more than I think we can defend here. What is solid is the narrower rule: if you are using a UUID as a primary key, use v7 rather than v4. A bigint sequence is still the default in most frameworks and still the cheapest option, and 16 bytes against 8 propagates into every foreign key and secondary index. The deciding question is usually not index performance but who generates the id. If it has to exist before the insert (distributed writers, offline clients, idempotency keys, merging data across databases) you need a client-generated id, and then v7 is the right kind. If the database can generate it, a sequence is fine.

A couple of smaller points while you are in there. UUIDv7 embeds the creation timestamp, so it leaks when a row was created, which is worth a line if these end up in public URLs. And columnDefinition = "uuid" is Postgres specific and bypasses the dialect, so I would drop it or state the assumption, since these snippets get copied verbatim.

Last, the checklist line:

- [ ] UUIDv7 (not random UUID v4) used for new entity primary keys where a Long sequence isn't required

These skills double as the rule set for automated PR review through skill-review, so a checklist line ends up being enforced literally. That one will flag ordinary sequence keys. Something closer to "random UUID v4 not used as the primary key of a large table" targets the actual defect.